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(54) Integrated software command specification and documentation system 



(57) An integrated software command specification 
and documentation system is disclosed. The user docu- 
mentation for a given input command or output report 
may be automatically generated by placing documenta- 
tion information directly in the software specification that 
defines the command or report. A list of documentation 
keywords and associated rules are utilized to identify and 
process the documentation information. A compiler will 
utilize the documentation keywords to recognize the doc- 
umentation information in the command specification 
and place the documentation information in an appropri- 
ate segment of a documentation file associated with the 
command or report. Documentation information that may 
be needed for a plurality of command specifications, 
such as parameter definitions for parameters associated 
with a plurality of commands, may be stored in a docu- 
mentation library. 
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Description 

FIELD OF THE INVENTION 

The present invention relates to a system for docu- 
menting software, and more particularly, to a method and 
apparatus for automatically generating user documenta- 
tion for software commands and output reports from doc- 
umentation information that has been placed directly in 
a software specification. 

BACKGROUND OF THE INVENTION 

While software may be the medium for communicat- 
ing with a computing system, it is the accompanying doc- 
umentation that will explain the operation of that software 
to those who wish to use it. Accordingly, the importance 
of clear and accurate documentation cannot be overem- 
phasized. In order to effectively utilize a particular soft- 
ware program or command, the documentation accom- 
panying that software should clearly set forth the pur- 
pose of the software and provide a detailed description 
of the input data and any output results, such as reports 
and displays, that are produced by the software. 

Because of the frequency with which many software 
programs are updated, programmers typically find it to 
be quite burdensome to keep the accompanying docu- 
mentation up to date. Nonetheless, it is critical that the 
documentation is properly revised with each software 
update so that the documentation may accurately reflect 
the operation of the software at all times. 

Unfortunately, with conventional programming tech- 
niques, a programmer will typically develop or modify a 
software program in a programming environment, and 
then the programmer or a third party must utilize a sep- 
arate environment, such as a text editor, to develop or 
modify the accompanying documentation. Accordingly, 
changes that are made in the software do not promptly, 
accurately and invariably appear in the accompanying 
documentation. 

One existing software documentation system, de- 
scribed in U.S. Patent No. 4,860,203 and hereinafter re- 
ferred to as the "Corrigan" system, allows design docu- 
mentation information for a software program to be 
placed directly in a high level language source code pro- 
gram for extraction by a compiler. The extracted docu- 
mentation information is sequentially placed by the com- 
piler in a separate design documentation file. In addition, 
the Corrigan software documentation system includes a 
mechanism to ensure that every implementation code 
statement of the software program has at least one as- 
sociated design comment describing the code operation. 

While the Corrigan software documentation system 
provides an effective mechanism for extracting docu- 
mentation information from a source code file, the ex- 
tracted documentation information may not be reorgan- 
ized by the compiler in any manner. The Corrigan soft- 
ware documentation system utilizes a single documen- 



tation indicator, i.e.. an exclamation mark, to identify doc- 
umental ion statements in the source code program. Ac- 
cordingly, the extracted documentation information can- 
not be classified or reorganized in any manner and must 
5 t be placed in a single design documentation file in the 
order in which it was extracted from the source code pro- 
gram. 

As is apparent from the above deficiencies with con- 
ventional documentation systems, a need exists for an 

10 improved documentation management system that is in- 
tegrated in a single environment with the programming 
tools and allows extracted documentation information to 
be processed or reorganized. An integrated program- 
ming and documentation system will make it easier for 

?5 programmers to write consistent and complete docu- 
mentation, and will thereby facilitate the maintenance of 
accurate documentation. 



20 



SUMMARY OF THE INVENTION 



Generally, according to one aspect of the invention, 
the documentation for a particular input command or out- 
put report may be automatically generated by placing 
documentation information directly in the software spec- 
ks ification that defines the command or report. 

The invention includes a method for generating user 
documentation for a software command to be executed 
by a computing system. The computing system will in- 
terpret the software command based on a high level lan- 
30 guage command specification that includes command 
specification information identified by one or more com- 
mand keywords. The high level language command 
specification is translated into a form that may be exe- 
cuted by the computing system and the user documen- 
ts tation includes a plurality of segments. The documenta- 
tion method comprises the steps of: defining a plurality 
of documentation keywords for identifying documenta- 
tion information statements in the command specifica- 
tion that describe the operation of the software com- 
40 mand, each of the documentation keywords being asso- 
ciated with one of the segments of the user documenta- 
tion; incorporating into the high level language command 
specification one or more of the documentation informa- 
tion statements, wherein each of the documentation in- 
^5 formation statements are identified in the command 
specification by one of the predefined documentation 
keywords; parsing the high level language command 
specification: extracting from Ihe parsed command spec- 
ification each of the documentation information state- 
50 ments identified by one of the predefined documentation 
keywords; and placing each of the extracted documen- 
tation information statements in the segment of the user 
documentation corresponding to the associated docu- 
mentation keyword. 
55 in addition, the invention includes an apparatus for 

generating user documentation for a software command 
to be executed by a computing system. The computing 
system interprets the software command based on a 
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high level language command specification that includes 
command specification information identified by one or 
more command keywords. The high level language com- 
mand specification is translated into a form that may be 
executed by the computing system. The documentation 
apparatus comprises: a documentation keyword data 
base for storing a plurality of documentation keywords 
for identifying documentation information statements in 
the command specification that describe the operation 
of the software command, each of the documentation 
keywords having an associated rule to be performed 
upon recognition of the associated documentation key- 
word in the command specification; means for incorpo- 
rating into the high level language command specifica- 
tion one or more of the documentation information state- 
ments, wherein each of the documentation information 
statements are identified in the command specification 
by one of the predefined documentation keywords; a 
parser for parsing the high level language command 
specification; and processor means for extracting from 
the parsed command specification each of the documen- 
tation information statements identified by one of the pre- 
defined documentation keywords and for processing 
each of the extracted documentation information state- 
ments based on the rule associated with the documen- 
tation keyword identifying the documentation information 
statement. 

A more complete understanding of the present in- 
vention, as well as further features and advantages of 
the invention, will be obtained by reference to the de- 
tailed description and drawings. 

BRIEF DESCRIPTION OF THE DRAWINGS 

FIG. 1 is a schematic block diagram illustrating an 
integrated software command specification and 
documentation system according to the present 
invention; 

FIGS. 2a through 2d, collectively, illustrate a sample 
command specification source code file that pro- 
vides specification and documentation information 
for an input command and associated output report; 

FIGS. 3a through 3e, collectively, are a flow chart 
describing an exemplary documentation process as 
utilized by a documentation file generator in analyz- 
ing a parse tree and generating user documentation; 

FIG. 4 is an illustrative command documentation file 
for the command specified in FIGS. 2a through 2d; 
and 

FIG. 5 is an illustrative report documentation file for 
a report generated by the command specified in 
FIGS. 2a through 2d. 



DETAILED DESCRIPTION 

An integrated software command specification and 
documentation system according to the present inven- 
5 tion is illustrated in FIG 1 . The integrated software com- 
mand specification and documentation system disclosed 
herein is a software generation system (SGS) based 
software development tool. The software generation 
system may be embodied as a compiler or a similar sys- 
io tern capable of translating command specifications into 
a machine readable format. 

As is well-known, a process or a series of computer 
instructions to be performed by a computing system 85 
may be initiated by a user at run-time by entering a soft- 
15 ware command 80 that is associated with the desired 
process or series of instructions. As discussed further 
below, the computing system 85 knows how to interpret 
the entered software command 80 based on a command 
specification 10 that has been previously processed by 
a compiler 1 5 at compile time. The software command 
80 may be entered by a user into the computing system 
85 by, for example, entering an alphanumeric label from 
a keyboard, depressing a function key on a keyboard, or 
selecting an icon using a graphical user interface. 

An illustrative command specification, such as the 
command specification 10, is discussed below, in con- 
junction with FIGS. 2a through 2d. Typically, the com- 
mand specification 10 is written in a high level language 
that is then translated into a computer readable form by 
a compiler, such as the compiler 1 5, as shown in FIG. 1 . 
As discussed further below the compiler 1 5 will analyze 
the command specification 10 at compile time and es- 
tablish an entry 90 in a command data base 35 for each 
specified command. 

As discussed further below, the entry 90 in the com- 
mand data base 35 for each software command 80 will 
typically identify the associated command and set forth 
the series of computer instructions that should be per- 
formed by the computing system 85 upon entry of the 
command 80 into the computing system 85 at run-time. 
Alternatively, the entry 90 can identify the process or se- 
ries of computer instructions that should be performed 
by the computing system 85 by storing an indication of 
where the desired process or series of computer instruc- 
tions is stored., such as a software file or other memory 
location. In addition, the entry 90 will typically include in- 
formation about any parameters that may be required to 
execute the command 50. In this manner, when a soft- 
ware command 80 is entered by a user into the comput- 
ing system 85 at run-time T the appropriate entry 90 in the 
command data base 35 may be accessed by the com- 
puting system 85 in order to properly execute the appro- 
priate process or scries of computer instructions. 

The computing system 85 may be embodied as any 
programmed digital data processor capable of receiving 
command inputs from a user and executing an associ- 
ated process or series of computer instructions, such as 
a general purpose computer executing applications soft- 
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ware or a dedicated program controlled processor, such 
as a telecommunications switch. 

As shown in FIG. 1 , the integrated software specifi- 
cation and documentation system preferably employs a 
compiler 15, as modified herein to provide documenta- 
tion generation facilities. A command specification 10 is 
received by the compiler 1 5 from an input medium, such 
as a computing system having programming tools or, al- 
ternatively, from a storage medium. 

The command specification 10 is analyzed at com- 
pile time by a parser 20 which converts the command 
specification 10 into a parse, which may take any one of 
a number of well-known forms, such as a parse tree 22. 
The operations of the parser 20, and the hierarchical re- 
lationship of the resultant parse tree 22, are well known 
to those skilled in the art. Generally, a compiler, such as 
the compiler 15, parses the command specification and 
analyzes the parse tree 22 by referencing a stored list of 
keywords and associated rules that must be performed 
upon recognition of a keyword in the parse tree 22. 

A file code generator 25 preferably consists of a 
processor 32 and a memory unit 34. As is well-known, a 
command specification process 28, stored in the mem- 
ory unit 34, is executed by the processor 32 to analyze 
the parse tree 22 by searching for predefined command 
keywords in the parse tree 22. The list of predefined com- 
mand keywords are stored in a command keyword data 
base 30, which may be an independent database in the 
memory unit 34, as shown in FIG 1 , or embedded in the 
code for the command specification process 28. For 
each predefined command keyword, the command key- 
word data base 30 stores an associated rule that must 
be performed by the command specification process 28 
upon recognition of the command keyword and associ- 
ated data in the parse tree 22. 

Typically, the command specification process 28 will 
search the parse tree 22 for command keywords asso- 
ciated with the specification information that is necessary 
to populate the entry 90 in the command data base 35 
for the respective command 80. As previously indicated, 
each entry 90 in the command data base 35 preferably 
includes a cell 92 that identifies the associated command 
and a cell 94 that sets forth the series of computer in- 
structions that should be performed by the computing 
system 85 upon entry of the command into the comput- 
ing system at run-time. Alternatively, the cell 94 can iden- 
tify the process or series of computer instructions that 
should be performed by the computing system 85 by 
stor ing an indication of where the desired process or se- 
ries of computer instructions is stored. In addition, the 
entry 90 will preferably include a cell 96 that will typically 
include information about any parameters that may be 
required to execute the command 80, such as the pa- 
rameter type, and the valid range of the parameter val- 
ues. 

In order for a software command to be effectively 
utilized by a user, the command must be properly docu- 
mented Typically, the user documentation associated 



with a command, hereinafter referred to as command 
documentation, includes a description of the purpose of 
the command, as well as a description of how to use the 
; command. The description of how to use the command 
s preferably includes a description ol the parameters as- 
sociated with the command. 

According to one feature of the invention, the com- 
mand documentation for a given command can be auto- 
matically generated by placing the necessary documen- 
10 tation information directly in the associated command 
specification together with one or more predefined doc- 
umentation keywords, as described below. 

A documentation file generator 40 preferably con- 
sists of a processor 42 and a memory unit 44. The mem- 
*5 ory unit 44 stores a documentation process 48, dis- 
cussed below in conjunction with FIGS. 3a through 3e, 
that is executed by the processor 42 to identify and an- 
alyze the documentation information that appears in the 
parse tree 22. Preferably, the list of predefined documen- 
20 tation keywords and associated rules are stored in a doc- 
umentation keyword data base 45, which may be an in- 
dependent data base in the memory unit 44, as shown 
in FIG. 1 , or embedded in the code for the documentation 
process 48. 

2 s As discussed further below, the documentation 

process 48 will search. the parse tree 22 in order to iden- 
tify documentation keywords and to extract the associ- 
ated documentation information. If the documentation 
process 48 identifies a documentation keyword in the 
30 parse tree 22, the appropriate rule associated with the 
documentation keyword will be performed by the docu- 
mentation process 48 on the data that has been placed 
with the associated documentation keyword in the re- 
spective node of the parse tree 22. In addition, as dis- 
ss cussed further below, the documentation process 48 
may implement rules requiring a certain portion of the 
source code to include documentation information there- 
by ensuring the consistency and completeness of the 
documentation. In a preferred embodiment, the docu- 
40 mentation file generator 40 will place the documentation 
information that has been identified in the parse tree 22 
in a command documentation file 400 or a report docu- 
mentation file 500, as discussed further below in con- 
junction with FIGS. 4 and 5. 
45 In a preferred embodiment, a documentation library 
75, which may be embodied as a software file stored in 
the memory unit 44 ; is provided to store parameter def- 
initions or other information that may be needed by a plu- 
rality of command specifications. Thereafter, the com- 
50 mand specification for each command that utilizes the 
parameter or other information will reference the more 
detailed information that is stored in the documentation 
library 75. In this manner, the effort needed to subse- 
quently define or modify the parameter for each com- 
55 mand is reduced and the consistency of the parameter 
definition for each command is ensured. 

It is to be understood that although the file code gen- 
erator 25 and the documentation file generator 40 of the 
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compiler 15 have been illustrated as employing two in- 
dependent processors 32, 42 and two independent 
memory units 34. 44, a single integrated processor or 
associated memory unit could be employed to imple; 
ment the command specification process 28 and the 
documentation process 48, as would be apparent to one 
skilled in the art. In addition, since there may be some 
overlap of the command keywords and the documenta- 
tion keywords, as discussed further below, the command 
keywords and documentation keywords, as well as the 
associated rules, may be stored in a single data base, 
that may be accessed by both the command specifica- 
tion process 28 and the documentatbn process 48. Fur- 
thermore, it is noted that the documentation library 75 
may be part of a broader library specification that may 
also include additional command specification informa- 
tion. 

A documentation processor 50 is preferably provid- 
ed to process the command and report documentation 
files 400, 500, respectively, generated by the documen- 
tation file generator 40 in order to generate formatted 
pages for a user documentation manual. Preferably, the 
documentation processor 50 will generate user docu- 
mentation manuals that conform to a style guide or an- 
other body of rules that govern the layout and content of 
the documentation information. The documentation 
processor 50 preferably presents the user documenta- 
tion to a user by means of a display 60 or a hard copy 
generated by a printer 65. 

In the embodiment discussed herein in conjunction 
with FIGS. 2 through 5, the documentation keyword data 
base 45 includes the following illustrative documentation 
keywords, discussed further below: PURPOSE, PA- 
RAMETER DESCRIPTION, WARNING, PAGE and RE- 
SPONSES. As discussed below in conjunction with the 
documentation process 48, shown in FIGS. 3a through 
3e, one or more documentation rules can optionally be 
defined for each documentation keyword. The documen- 
tation rules can allow the associated documentation 
statements to be reorganized for placement in the user 
documentation, as well as maintain the consistency and 
completeness of the user documentation. The list of doc- 
umentation keywords may be supplemented by adding 
additional keywords and associated documentation 
rules to the documentation keyword data base 45, as 
would be apparent to one skilled in the art. 

An illustrative command specification 10 for a com- 
mand, op-wspos, is shown in FIGS. 2a through 2d. The 
SPECIFICATION keyword in line 02 of FIG. 2a is an in- 
dication to the compiler 1 5 that the software being proc- 
essed is a specification for a given input command or 
output report. The PAGE keywords in lines 04 and 16 of 
FIG. 2a provide a mechanism for allowing a programmer 
to specify a particular page or section of a documentation 
manual where the documentation for a particular com- 
mand or report should appear. For example, a program- 
mer may desire to group the documentation for a number 
of related commands or reports on a single page. 



Thus, lines 04 through 14 specify the PAGE require- 
ments for the op-wspos command, and lines 1 6 through 
26 specify the PAGE requirements for the associated 
op-wspos report. The part and subject fields of the PAGE 

5 specification, as shown in lines 06 and 18 and lines 08 
and 20 of the specification of FIG. 2a, respectively, allow 
the programmer to specify the chapter and section, re- 
spectively, where the documentation information for the 
current command or report should appear. 

io in addition, if the command or report indicated in 
lines 1 2 and 24, respectively, are particularly relevant to 
one or more features of a computing system, the pro- 
grammer may specify this information in the features 
field, as shown in lines 10 and 22 of the specification of 

is FIG. 2a. The pathname field in lines 14 and 26 indicate 
where the command and report documentation files for 
the associated command and report, respectively, are 
stored. It is noted that if a programmer would like docu- 
mentation for a plurality of commands or reports to ap- 

20 pear on the same documentation page, the information 
indicated in line 12 and line 24, respectively, can include 
a list of the desired commands or reports to appear on 
the same page. 

The COMMAND keyword in line 30 is an indication 

25 to the compiler 1 5 that lines 30 through 1 60 of the spec- 
ification will define a command. The INITIATION MES- 
SAGE keyword in line 30, together with the entry in line 
40, provide a mechanism for associating the command 
label with the process or series of computer instructions 

30 that should be performed by the computing system 85 
When the associated software command 80 is entered 
into the computing system 85 at run-time, the computing 
system 85 will retrieve the indication from the command 
data base 35 of how the desired process or series of 

35 computer instructions is initiated and thereafter send the 
appropriate message to execute the associated se- 
quence of instructions. Alternatively, line 40 could list the 
series of computer instructions that should be performed 
by the computing system 85 at run-time. 

40 The TEMPLATE keyword in line 50 provides a tem- 
plate for the usage of the command and associated pa- 
rameters, and indicates to the compiler that the input 
command and parameters must follow the syntax set 
forth in line 60, in a known manner. The command name 

45 and parameter information that appears in line 60 will 
typically be placed by the compiler 15 in the command 
data base 35, as previously indicated. In addition, the 
TEMPLATE information will be placed in the command 
documentation file 400, as described below. 

50 The PURPOSE keyword in line 70 is a documenta- 

tion keyword that will provide an indication to the com- 
piler 1 5 that the character string that follows in line 80 is 
a description of the purpose of the command and should 
appear in the command documentation, as described 

55 below. 

Lines 90 through 140 of the command specification 
define the type and range requirements of the numeric 
command parameter, tp. in a known manner. The PA- 
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RAMETER DESCRIPTION keyword in line 1 50 is a doc- 
umentation keyword that indicates to the compiler 1 5 that 
the character string that tollows in line 160 is a descrip- 
tion of the associated command parameter and should 
appear in the command documentation, as described 
below. The defined parameter information would typical- 
ly be placed by the compiler 15 in the command data 
base 35, as previously indicated. 

Very often, when a software command 80, such as 
the op-wspos command specified in FIGS. 2a through 
2d, is entered into a computing system 85 at run-time, 
the computing system 85 will take an action based on 
the input command 80 and then produce an output, such 
as a printed or displayed report. In order for the report to 
be effectively utilized and understood by a user, the re- 
port must be properly documented. Typically, the user 
documentation associated with a report, hereinafter re- 
ferred to as the report documentation, includes a de- 
scription of the meaning and format of the report. 

As is well-known, when the execution of a command 
80 produces an associated report, the command speci- 
fication 10 will typically include a specification of the as- 
sociated report, as discussed further below. As shown in 
FIGS. 2a through 2d, the command specification 10 as- 
sociated with the op-wspos command will include a re- 
port specification portion in lines 200 through 890, as in- 
dicated by the REPORT keyword in line 200 (FIG. 2b). 

The INITIATION MESSAGE keyword in line 210 of 
the command specification provides a mechanism for 
associating the report with the message in line 220 that 
will initiate the generation of the desired report, in a 
known manner. The message in line 220 will typically be 
placed by the compiler 15 in the command data base 35. 

The TEMPLATE keyword in line 230 indicates to the 
compiler 15 that lines 240 through 270 of the command 
specification provide a template for the report format. 
Lines 240 through 260 provide the report headings, and 
line 270 indicates the parameter values that should be 
utilized to populate the report, in a known manner. 

The PURPOSE keyword in line 280 of the specifica- 
tion is a documentation keyword that will provide an in- 
dication to the compiler 15 that the character string that 
follows in line 290 is a description of the report, that 
should appear in the report documentation, as described 
below. 

Lines 300 through 890 of the specification shown in 
FIGS. 2b through 2d define the type and range require- 
ments of each of the parameters that appear in the 
op-wspos report, in a known manner. The PARAMETER 
DESCRIPTION keywords in lines 360. 440, 520, 600, 
680 and 880 indicate to the compiler 15 that the charac- 
ter strings that follow are descriptions of the report pa- 
rameters, as described above. Similarly, the parameter 
mode accepts one of four character string inputs, as set 
forth in the enumerated list in lines 720 through 840, in 
a known manner. The DESC keywords below each 
ENUM keyword, such as in lines 750, 780, 810 and 840, 
provide an indication to the compiler 15 that the charac- 



ter string that follows is a description of the associated 
mode value. 

The documentation process 48 embodying the prin- 
ciples of the present invention, illustrated in FIGS. 3a 
s through 3e. will be entered at step 300 to analyze the 
command specification parse tree 22. It is to be under- 
stood that although the documentation process 48 is dis- 
cussed below using a set of illustrative command and 
documentation keywords, other keywords could be uti- 
io lized without departing from the scope or spirit of the in- 
vention, as will be apparent to one skilled in the art from 
the present discussion of the invention. 

A test is performed during step 302 to determine if 
the command specification parse tree 22 includes a 
15 PAGE keyword. The PAGE keyword will preferably allow 
a programmer to define a particular page or section of a 
documentation manual where the documentation for a 
particular command or report should appear. For exam- 
ple, a programmer may desire to group the documenta- 
20 tion for a number of related commands and reports on a 
single page. If it is determined during step 302 that the 
command specification parse tree 22 does include a 
PAGE keyword, the documentation process 48 will proc- 
ess the PAGE information and identify during step 303 
25 the fist of commands or reports that should appear on 
the same documentation page, as well as the appropri- 
ate page or section where the current documentation 
should be placed. 

A test is then performed during step 304 to deter- 
30 mine if there are additional PAGE keywords in the current 
specification parse tree to be processed. If it is deter- 
mined during step 304 that there are additional PAGE 
keywords to be processed, program control will return to 
step 302 and continue in the manner described above. 
35 if, however, it is determined during step 304 that 
there are no additional PAGE keywords to be processed, 
or if it was determined during step 302 that the command 
specification parse tree 22 does not include any PAGE 
keywords, then program control will proceed to step 305. 
40 A test is performed during step 305 to determine if 
the command specification parse tree 22 includes the 
COMMAND keyword, indicating that a command is be- 
ing specified. If it is determined during step 305 that the 
command specification parse tree 22 does not contain 
45 the COMMAND keyword, program control will proceed 
to step 360 (FIG. 3d). 

If it is determined during step 305 that the command 
specification parse tree 22 does contain the COMMAND 
keyword, the documentation process 48 will enforce any 
50 command documentation rules, and then copy the com- 
mand syntax and parameter information during step 310 
from the TEMPLATE segment of the command specifi- 
cation parse tree 22, such as would be associated with 
line 60 of FIG. 2a, into a header segment 410 of a com- 
55 mand documentation file 400, as discussed further be- 
low in conjunction with FIG. 4, that is created for storing 
the documentation information associated with the com- 
mand. The command documenlation file 400 being de- 
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veloped during execution of the documentation process 
48 may be stored in the memory unit 44 

A test is performed during step 315 to determine it 
the command specification parse tree 22 includes a 
WARNING keyword, which would allow the programmer 
to provide a warning to a user regarding the initiation of 
the command. If it is determined during step 31 5 that the 
command specification parse tree 22 does include a 
WARNING keyword, the documentation process 48 will 
enforce any warning documentation rules that have been 
defined and then copy the associated character string 
from the parse tree 22 during step 320 into a warning 
segment 415 of the command documentation file 400 as- 
sociated with the command, as discussed further below 
in conjunction with FIG. 4. 

If it is determined during step 31 5 that the command 
specification parse tree 22 does not include a WARNING 
keyword, an indication that there are no warnings is pref- 
erably placed in the warning segment 415 of the com- 
mand documentation file 400 during step 322, as dis- 
cussed further below in conjunction with FIG. 4. In addi- 
tion, an error message could also be generated during 
step 322, as an indication to the person documenting the 
software that no warnings have been provided for the 
execution of this command. 

A test is performed during step 325 (FIG. 3b) to de- 
termine if the command specification parse tree 22 in- 
cludes a PURPOSE keyword. If it is determined during 
step 325 that the command specification parse tree 22 
does not include a PURPOSE keyword, a test is per- 
formed during step 328 to determine if the command 
specification for the current command should include a 
PURPOSE keyword and associated documentation in- 
formation. Under certain circumstances, the purpose 
documentation information for a given command may be 
obtained from another location or a default purpose mes- 
sage may be utilized. For example, as discussed above, 
the documentation for a number of related commands 
may be grouped on a single page. Accordingly, it may 
be desired to indicate a single purpose for the group of 
commands, without indicating the purpose of each indi- 
vidual command. 

If it is determined during step 328 that the PUR- 
POSE keyword and associated documentation informa- 
tion is not necessary for this command, program control 
will proceed to step 340. If : however, it is determined dur- 
ing step 328 that the PURPOSE keyword is necessary 
for this command, an error or warning message should 
be generated during step 330, in order to ensure the 
completeness of the command documentation. Thereaf- 
ter, program control will proceed to step 340, described 
below. 

If, however, it is determined during step 325 that the 
command specification parse tree 22 does include a 
PURPOSE keyword, the documentation process 48 will 
enforce any purpose documentation rules and then copy 
the associated character string from the parse tree 22 
during step 335 into a purpose segment 420 of the com- 



mand documentation file 400 associated with the com- 
mand, as discussed further below in conjunction with 
FIG. 4. 

A test is performed during step 337 to determine if 
s there are additional PURPOSE keywords to be proc- 
essed for this command. !f it is determined during step 
337 that there are additional PURPOSE keywords to be 
processed, program control will return to step 325 and 
continue in the manner described above. 

io |f, however, it is determined during step 337 that 
there are no additional PURPOSE keywords to be proc- 
essed, a test is performed during step 340 to determine 
if the command has associated parameters, as indicated 
in the TEMPLATE segment analyzed during step 310. If 

15 it is determined during step 340 that the command does 
not have associated parameters, program control will 
proceed to step 350 (FIG. 3c). described below. 

If, however, it is determined during step 340 that the 
command does have associated parameters, a test is 

20 performed during step 342 to determine if the first de- 
fined parameter has a PARAMETER DESCRIPTION 
keyword. It is noted that if the command specification 10 
indicates that the parameter currently being analyzed is 
an enumerated list, the appropriate keyword identifying 

25 the description for each alternative character string will 
be DESC, such as in lines 750, 780, 810 and 840 of the 
command specification illustrated in FIG. 2a through 2d. 

If it is determined during step 342 that the command 
specification parse tree 22 does not include a PARAM- 

30 ETER DESCRIPTION keyword for the first defined pa- 
rameter, a test is performed during step 343 to determine 
if the command specification parse tree should include 
a PARAMETER DESCRIPTION keyword for the first de- 
fined parameter. Under certain circumstances, the doc- 

35 umentation information for a given parameter may be ob- 
tained from another location, such as the documentation 
library 75, or a default parameter description message 
may be utilized. 

If it is determined during step 343 that the PARAM- 

-40 ETER DESCRIPTION keyword is not necessary for the 
first defined parameter, program control will proceed to 
step 350 (FIG. 3c). If, however, it is determined during 
step 343 that the PARAMETER DESCRIPTION keyword 
is necessary for the first defined parameter, an error or 

^5 warning message should be generated during step 344, 
in order to ensure the completeness of the command 
documentation. Thereafter, program control will proceed 
to step 350 (FIG 3c), as described below. 

If, however, it is determined during step 342 that the 

50 command specification parse tree 22 does include a PA- 
RAMETER DESCRIPTION keyword for the first defined 
parameter, the documentation process 48 will enforce 
any parameter documentation rules and copy the asso- 
ciated character string from the parse tree 22 during step 

55 346 into an explanation of parameter segment 425 of the 
command documentation file 400 associated with the 
command, as discussed further below in conjunction 
with FIG. 4 
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A test is performed during step 348 to determine if 
there are additional parameters to be documented for 
this command. If it is determined during step 348 that 
there are additional parameters to be documented, pro-; 
gram control will return to step 342 and continue in the 
manner described above. 

If, however, it is determined during step 348 that 
there are no additional parameters to be documented, a 
test is performed during step 350 (FIG. 3c) to determine 
if the command specification parse tree 22 includes a 
RESPONSES keyword. The RESPONSES keyword will 
preferably allow a programmer to document the expect- 
ed system response to the entry of the command, such 
as an acknowledgement. If it is determined during step 
350 that the command specification parse tree 22 does 
not include a RESPONSES keyword, an indication that 
only standard system responses apply is preferably 
placed in a response segment 430 of the command doc- 
umentation file 400 during step 352, as discussed further 
below in conjunction with FIG. 4. 

If, however, it is determined during step 350 that the 
command specification parse tree 22 does include a RE- 
SPONSES keyword, the documentation process 46 will 
enforce any responses documentation rules and then 
copy the associated character string from the parse tree 
22 during step 354 into the responses segment 430 of 
the command documentation file 400 associated with the 
command, as discussed further below in conjunction 
with FIG. 4 

A test is performed during step 355 to determine if 
there are additional COMMAND keywords in the current 
specification to be processed for this command. If it is 
determined during step 355 that there are additional 
COMMAND keywords to be processed, program control 
will return to step 305 (FIG. 3a) and continue in the man- 
ner described above. 

If, however, it is determined during step 355 that 
there are no additional COMMAND keywords to be proc- 
essed, program control will proceed to step 360 (FIG 
3d). 

A test is performed during step 360 (FIG. 3d) to de- 
termine if the command specification parse tree 22 in- 
cludes a REPORT keyword, indicating that a report for- 
mat is being specified. If it is determined during step 360 
that the command specification parse tree 22 does not 
contain the REPORT keyword, program control will pro- 
ceed to step 385 (FIG. 3e), where the process will be 
exiled. 

If it is determined during step 360 that the command 
specification parse tree 22 does contain the REPORT 
keyword, the documentation process 48 will enforce any 
report documentation rules and then copy the report 
heading and parameter information from the TEMPLATE 
segment of the specification parse tree 22, such as as- 
sociated with lines 240 through 270 of FIG. 2b, into a 
header segment 510 of a report documentation file 500 
that is created for storing the documentation information 
associated with the report during step 362, as discussed 



further below in conjunction with FIG. 5. The report doc- 
umentation file 500 being developed during execution of 
the documentation process 48 may be stored in the 
memory unit 44. 

A test is performed during step 364 to determine if 
the command specification parse tree 22 includes a 
PURPOSE keyword associated with the report specifi- 
cation. If it is determined during step 364 that the spec- 
ification parse tree 22 does not include a PURPOSE key- 
io word for the report specification, a test is performed dur- 
ing step 365 to determine if the specification for the cur- 
rent report should include a PURPOSE keyword and as- 
sociated documentation information. Under certain cir- 
cumstances, the purpose documentation information for 
15 a given report may be obtained from another location or 
a default purpose message may be utilized. For exam- 
ple, as discussed above, the documentation for a 
number of related reports may be grouped on a single 
page. Accordingly, it may be desired to indicate a single 
20 purpose for the group of reports, without indicating the 
purpose of each individual report. 

If it is determined during step 365 that the PUR- 
POSE keyword is not necessary for this report, program 
control will proceed to step 370 (FIG. 3e). If, however, it 
25 is determined during step 365 that the PURPOSE key- 
word is necessary for this report, an error or warning 
message should be generated during step 366, in order 
to ensure the completeness of the command documen- 
tation. Thereafter, program control will proceed to step 
30 370 (FIG. 3e), as described below. 

If, however, it is determined during step 364 that the 
command specification parse tree 22 does include a 
PURPOSE keyword for the report specification, the doc- 
umentation process 48 will enforce any purpose docu- 
35 mentation rules and then copy the associated character 
string from the parse tree 22 during step 368 into a pur- 
pose segment 515 of the report documentation file 500 
associated with the report, as discussed further below in 
conjunction with FIG. 5. 
•*o A test is performed during step 369 to determine if 
there are additional PURPOSE keywords to be proc- 
essed for this report. If it is determined during step 369 
that there are additional PURPOSE keywords to be proc- 
essed, program control will return to step 364 and con- 
■*s tinue in the manner described above. 

If, however it is determined during step 369 that 
there are no additional PURPOSE keywords to be proc- 
essed, program control will proceed to step 370 (FIG. 
3e). 

50 a test is performed during step 370 (FIG. 3e) to de- 

termine if the report has associated parameters, as indi- 
cated in the TEMPLATE segment analyzed during step 
362. If it is determined during step 370 that the report 
does not have associated parameters, program control 

55 W in proceed to step 380, discussed below. 

If, however it is determined during step 370 that the 
report does have associated parameters, a test is per- 
formed during step 372 to determine if the first defined 
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parameter for the report has a PARAMETER DESCRIP- 
TION keyword. It is noted that if the command specifica- 
tion 10 indicates that the parameter currently being an- 
alyzed is an enumerated list, the appropriate keyword 
identifying the description for each alternative character 
string will be DESG such as in lines 750, 780, 810 and 
840 of the command specification illustrated in FIG. 2a 
through 2d. 

If it is determined during step 372 that the command 
specification parse tree 22 does not include a PARAM- 
ETER DESCRIPTION keyword for the first defined pa- 
rameter, a test is performed during step 373 to determine 
if the command specification parse tree should include 
a PARAMETER DESCRIPTION keyword for the first de- 
fined parameter for the report. Under certain circum- 
stances, the documentation information for a given pa- 
rameter for a report may be obtained from another loca- 
tion such as the documentation library 75, or a default 
parameter description message may be utilized. 

If it is determined during step 373 that the PARAM- 
ETER DESCRIPTION keyword is not necessary for the 
first defined parameter for the report, program control will 
proceed to step 330. If, however, it is determined during 
step 373 that the PARAMETER DESCRIPTION keyword 
is necessary for the first defined parameter for the report, 
an error or warning message should be generated during 
step 374, in order to ensure the completeness of the 
command documentation. Thereafter, program control 
will proceed to step 380. as described below. 

If, however, it is determined during step 372 that the 
command specification parse tree 22 does include a PA- 
RAMETER DESCRIPTION keyword for the first defined 
parameter, the documentation process 48 will enforce 
any parameter documentation rules and then copy the 
associated character string from the parse tree 22 during 
step 376 into an explanation of parameter segment 520 
of the report documentation file 500 associated with the 
report, as discussed further below in conjunction with 
FIG. 5. 

A test is performed during step 378 to determine if 
there are additional parameters to be documented for 
this report. If it is determined during step 378 that there 
are additional parameters to be documented, program 
control will return to step 372 and continue in the manner 
described above. 

If, however, it is determined during step 378 that 
there are no additional parameters to be documented, a 
lest is performed during step 380 to determine if there 
are additional REPORT keywords in the current specifi- 
cation to be processed for this report. If it is determined 
during step 378 that there are additional REPORT key- 
words to be processed, program control will return to 
step 360 (FIG. 3d) and continue in the manner described 
above. 

If, however, it is determined during step 378 that 
there are no additional REPORT keywords to be proc- 
essed, program control will proceed to step 385, where 
the process will be exited 



When the documentation process 48 of FIGS. 3a 
through 3e has been performed on the command spec- 
ification for the op -wspos command, shown in FIGS. 2a 
through 2d. a command documentation file, such as the 
s command documentation file 400 shown in FIG. 4, wilt 
result. As previously indicated, the documentation proc- 
ess will analyze the command specification parse tree 
22 to identify certain documentation information that 
should be extracted from the parse tree 22 and placed 
10 jn various segments of the command documentation file 
400. As shown in FIG. 4, the command documentation 
file 400 will preferably include a header segment 410, a 
warning segment 415, a purpose segment 420, an ex- 
planation of parameters segment 425 and a response 
is segment 430. In addition, the command documentation 
tile 400 may also include directions to the printer 65, such 
that when the command documentation file 400 is print- 
ed, it will contain certain features, such as a box around 
the header segment 410 and the warning segment 41 5. 

Similarly, following execution of the documentation 
process of FIGS 3a through 3e on the command spec- 
ification for the op -wspos command, shown in FIGS. 2a 
through 2d, a report documentation file, such as the re- 
port documentation file 500 shown in FIG. 5 : will result. 
As previously indicated, the documentation process will 
analyze the command specification parse tree 22 to 
identify certain documentation information that should be 
extracted from the parse tree 22 and placed in various 
segments of the report documentation file 500. As shown 
in FIG. 5, the report documentation file 500 will preferably 
include a header segment 510, a purpose segment 515 
and an explanation of parameters segment 520. In ad- 
dition, the report documentation file 500 may also include 
directions to the printer 65, such that when the report 
documentation file 500 is printed, it will contain certain 
features, such as a box around the header segment 51 0. 

As previously indicated, the documentation files 
generated by the documentation file generator 40, such 
as the command documentation file 400 shown in FIG. 
4 or the report documentation file 500 shown in FIG. 5, 
may be formatted in a desired manner by the documen- 
tation processor 50. 

It is to be understood that the embodiments and var- 
iations shown and described herein are illustrative of the 
principles of this invention only and that various modifi- 
cations may be implemented by those skilled in the art 
without departing from the scope of the invention. 



Claims 

1. A method for generating user documentation for a 
software command to be executed by a computing 
system, said computing system interpreting said 
software command based on a high level language 
command specification that includes command 
specification information identified by one or more 
command keywords, said high level language com- 
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mand specification being translated into a form that 
may be executed by said computing system, said 
user documentation having a plurality of segments, 
said documentation method comprising the steps of; 

defining a plurality of documentation keywords s 
for identifying documentation information state- 
ments in said command specification that describe 
the operation of said software command, each of 
said documentation keywords being associated with 
one of said segments of said user documentation; w 

incorporating into said high level language 
command specification one or more of said docu- 
mentation information statements, wherein each of 
said documentation information statements are 
identified in said command specification by one of is 
said predefined documentation keywords; 

parsing said high level language command 
- specification; 

extracting from said parsed command specifi- 
cation said documentation information statements 20 
identified by one of said predefined documentation 
keywords; and 

placing said extracted documentation informa- 
tion statements in said segment of said user docu- 
mentation corresponding to said associated docu- 25 
mentation keyword. 

2. The documentation method according to claim 1, 
wherein said execution of said software command 

by said computing system produces an output result 30 
and wherein said command specification includes 
specification information that defines said output 
result, and wherein said step of incorporating docu- 
mentation information statements in said command 
specification further includes the step of incorporat- 35 
ing documentation information statements that 
describes said output result. 

3. The documentation method according to claim 2, 
wherein at least one of said segments in said user 40 
documentation is an output documentation seg- 
ment, and wherein said documentation information 
statements describing said output result are placed 

in said output documentation segment. 

45 

4. The documentation method according to claim 1, 
wherein at least one of said predefined documenta- 
tion keywords provides an indication that said asso- 
ciated documentation information statement pro- 
vides a description of the purpose of said software so 
command. 

5. The documentation method according to claim 1, 
wherein said command specification further 
includes specification information that defines one 55 
or more parameters associated with said software 
command and wherein at least one of said docu- 
mentation information statements includes a 



description of said one or more parameters. 

6. The documentation method according to claim 5. 
wherein one or more of said parameter descriptions 
are stored in a documentation library that may be 
accessed to generate said user documentation. 

7. The documentation method according to claim 1 , 
further including the step of processing said user 
documentation to generate one or more formatted 
pages for a user documentation manual. 

8. The documentation method according to claim 1 , 
further including the step of ensuring that said com- 
mand specification includes at least one of said doc- 
umentation information statements describing the 
operation of said software command. 

9. A method for generating user documentation for a 
software command to be executed by a computing 
system, said computing system interpreting said 
software command based on a high level language 
command specification that includes command 
specification information identified by one or more 
command keywords, said high level language com- 
mand specification being translated into a form that 
may be executed by said computing system, said 
documentation method comprising the steps of: 

defining a plurality of documentation keywords 
for identifying documentation information state- 
ments in said command specification that describe 
the operation of said software command, each of 
said documentation keywords having at least one 
associated rule to be performed upon recognition of 
said associated documentation keyword in said 
command specification; 

incorporating into said high level language 
command specification one or more of said docu- 
mentation information statements, wherein each of 
said documentation information statements are 
identified in said command specification by one of 
said predefined documentation keywords; 

parsing said high level language command 
specification: 

extracting from said parsed command specifi- 
cation said documentation information statements 
identified by one of said predefined documentation 
keywords: and 

processing said extracted documentation 
information statements based on said rule associ- 
ated with said "documentation keyword identifying 
said documentation information statement. 

10. The documentation method according to claim 9, 
wherein one or more of said rules associated with 
said documentation keywords require said extracted 
documentation information statements to be con- 
sistent with standards established for said associ- 
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11. The documentation method according to claim 9. 
wherein said rules associated with said documenta- 
tion keywords require documentation information $ 
statements to be provided for less than all of said 
command specification statements. 

12. The documentation method according to claim 9, 

, wherein said user documentation includes a plurality io 
of segments and wherein each of said predefined 
documentation keywords is associated with one of 
said segments of said user documentation. 

13. The documentation method according to claim 12, is 
wherein said processing step further includes the 
step of placing each of said extracted documenta- 
tion information statements in said segment of said 
user documentation corresponding to said associ- 
ated documental ion keyword. 20 

14. The documentation method according to claim 12, 
wherein said rule associated with each predefined 
documentation keyword includes an indication of 
which of said segments of said user documentation 25 
where said associated extracted documentation 
information statement should be placed. 
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SPECIFICATION 

PAGE { 

part : 
subj ect : 
features 
commands 
pathname 

} 

PAGE { 

part : 
subj ect : 
features : 
reports : 
pathname : 

} 

COMMAND { 



20; 
65; 

aOOOO ; 
op-wspos ; 

cdoc/5cr/TMcmd/op-wspos; 

20; 
65; 

aOOOO; 
op_wspos ; 

cdo c / 5 c r / TMrp t / op_wspos ; 



INITIATION MESSAGE 
MGWSPOS; 



} 



} 



TEMPLATE 
op-wspos : 

\ 

PURPOSE { 



{ 

tp; 



} 



■Prints the current defaults for 
the indicated trunk and line 
work station (TLWS) test 
position (TP) . " ; 



PARAMETER tp{ 

PARAMETER TYPE { 
doma i n : num ; 
min : 1 ; 
max: 32; 
default: -1; 
} 

PARAMETER DESCRIPTION { 

"Trunk and line workstation 



test position number 
} 



(1-32) . 



FIG. 2a 
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20 0 REPORT { 

210 INITIATION MESSAGE { 

22 0 MGWSPOS; 

} 

23 0 TEMPLATE { 

240 proto: "OP WSPOS"; 

250 proto: "TP" !"ID" ! "TO" ! "FREQ" ! n LVL" 

! n T&M MODE" ! "OPD" ; 

2 60 prOtO: "--« |n„,» |n..n j fl „ , „ „ 

I " n | n it 

• ; 

270 proto: tp !id !to Ifreq ! lvl !mode 

! opd; 

} 

280 PURPOSE { 

290 "To list the current default of a 

TLWS (trunk and line workstation) 
TP (test position) . This report 
is generated as a result of an 
OP-WSPOS command . n 

) 

300 PARAMETER tp { 

310 PARAMETER TYPE { 

320 domain: num; 

33 0 min: 1; 

340 max: 32; 

350 default: -1; 

} 

360 PARAMETER DESCRIPTION ( 

370 "TLWS TP number (1-3 2) . " 

} 

} 

380 PARAMETER id { 

390 PARAMETER TYPE { 

400 dom: num; 

410 min : i; 

420 max: 32; 

430 default: 0; 

} 

440 PARAMETER DESCRIPTION { 

450 -TP identification number" 

} 



FIG. 2b 
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460 PARAMETER to { 

47 0 PARAMETER TYPE { 

480 domain: num; 

490 min: 1; 

500 max: 100; 

510 default: 1; 

} 

520 PARAMETER DESCRIPTION { 

53 0 "Time in hours before the TP 

will timeout. " 

} 

} 

540 PARAMETER freq { 

550 PARAMETER TYPE { 

560 domain: num; 

570 min: 0; 

580 max: 4095; 

590 default: -1; 

} 

600 PARAMETER DESCRIPTION { 

610 "Frequency in hertz." 

} 

} 

620 PARAMETER lvl { 

63 0 PARAMETER TYPE { 

640 domain: num; 

650 min : 0 ; 

660 max: 490; 

67 0 default: -1; 

} 

680 PARAMETER DESCRIPTION { 

690 "Level in decibels." 

} 

} 



FIG. 2c 
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700 PARAMETER mode { 
710 PARAMETER TYPE { 

720 domain: ENUMLIST 

730 ENUM TALK { 

740 text: "TALK"; 

750 desc: "User can talk and listen."; 

7 60 ENUM MONITOR { 

770 text: "MNTR" ; 

780 desc: "user can only listen." ; 

} 

790 ENUM TEST { 

800 text: "TEST"; 

810 desc: "Phone on hold."; 

} 

82 0 ENUM NONE { 

830 text: "NONE"; 

840 desc: "No T&M phone in use."; 

} 

} 

} 

850 PARAMETER opd { 

860 PARAMETER TYPE { 

870 domain : dn ; 

} 

880 PARAMETER DESCRIPTION { 

890 "Outpulse digits. ■ 

} 

} 



FIG. 2d 
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300 




Analyze command 
specification parse tree 




302 



303 




Identify list of commands or reports that should appear 
on same documentation page, and appropriate section 
or page where documentation should appear 



Yes 




From FIG 



<§) To FIG. 3d 



Enforce command documentation rules, if any, and copy command syntax 
and parameter information from TEMPLATE segment of command specification 
into a header segment of a documentation file associated with the command 



315 



322 




Yes 



Enforce warning documentation 
rules, if any, and copy associated 
character string into a warning 
segment of documentation file 



Place indication that there are 

no warnings in warning 
segment of documentation file 



\ 

320 



FIG. 3a 



CJTo FIG. 3b 
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(C) From FIG. 3a 




Enforce purpose documentation 
rules, if any, and copy associated 

character string into a purpose 
segment of the documentation file 



337 



Are 

Yes — there additional 

PURPOSE keywords to be, 
processed 7 



340 



Does 
the command have" 
associated parameters^ 



No 



FIG. 3b 



Yes 



343 



342 



346 



PARAMETER" 
DESCRIPTION 
.keyword"?. 



No 



Is 

PARAMETEI 
DESCRIPTION 

keyword 
.necessary?/ 



Yes 



Enforce parameter documentation rules, if 

any, and copy associated character 
string into an explanation of parameters 
segment of the documentation file 




No 



To FIG. 3c 
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D)From FIG. 3b 




352 



Place an indication that 
only standard responses 
apply in a response segment 
of documentation file 



Enforce responses documentation 
rules, if any, and copy associated character 
string into a response segment of 
the documentation file 



355 



Are 

there additional" 
COMMAND keywords to^ 
be processed ? 

No 

:B) To FIG. 3d 



Yes 



<A)ToFIG. 3a 



FIG. 3c 
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B) From FIG. 3a, 3c or 3e 




•©To FIG. 3e 



Enforce report documentation rules, if any, and 
copy command name report heading and 
parameter information from TEMPLATE segment 
of report specification into a header segment of 
a documentation file associated with the report 




Enforce purpose documentation rules, 
if any, and copy associated character 
string into a purpose segment 
of the report documentation file 



Are 

Yes ^-"there additionaT „ 
^URPOSE keywords to 
^be processed ? 



To FIG. 3e 



369 



FIG. 3d 
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T) From FIG. 3d 




374 

V 

Generate 

error 
message 



Enforce parameter documentation rules, if any, and 
copy associated character string into an explanation 
of parameters segment of the documentation file 



378 

Yes^^ > ~'~~^~A re there 

additional parameters to beT 
documented?^ 



380 

Are there 
^additional REPORT keywords* 
to be processed ? 



No 



Yes 



385 



NoI« (E) From FIG. 3d 

EXIT V 



<B)To FIG. 3d 



FIG. 3e 
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OP-WSPOS COMMAND DOCUMENTATION FILE 



410 — ^ 

^-OP-WSPOS: TP = a 

415"^— Warning: none 



PURPOSE 

Prints the current defaults for the indicated trunk and 
line workstation (TLWS) test position (TP). 



■ EXPLANATION OF PARAMETERS 
a = Trunk and line workstation test position number (1-32). 



■ • 



RESPONSES 

Only standard system responses apply. 



FIG. 4 
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OP-WSPOS REPORT DOCUMENTATION FILE 

OP WSPOS 

TP ID TO FREQ LVL T&M MODE OPD 
a b c d e f g 



• REPORT PURPOSE 
To list the current defaults of a TLWS (trunk and line work station) 
TP (test position). This report is generated as a result of an 
OP-WSPOS command. 



► EXPLANATION OF PARAMETERS 
a = TLWS TP number (1-32). 
b = TP identification number, 
c = Time in hours before the TP will timeout, 
d = Frequency in hertz, 
e = Level in decibels, 
f = T&M (talk and monitor) phone mode. 

MNTR - User can only listen. 

NONE - No T&M phone in use. 

TALK - User can talk and listen. 

TEST - Phone on hold, 
g = Outpulse digits. 
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SPECIFICATION 

PAGE { 

part : 
subject : 
features 
commands 
pathname 

> 

PAGE { 

part : 
subject : 
features ; 
reports : 
pathname: 

} 

COMMAND ( 



20; 
65; 

aOOOO; 
op-wepos; 

cdoc/Scr/nicmd/op-wspos ; 
20; 

65; 

aOOOO; 
op_wspos ? 

c doc / 5 c r / TMrp t / op_i\/spo a ; 



INITIATION MESSAGE 
MGWSPOS? 



TEMPLATE 
Gp-wspas ; 

PURPOSE £ 



{ 

tpj 



'Prints the current defaults for 
the indicated trunk and line 
work station (TL-WS) teat 
position (TP) . 



PARAMETER tp{ 

PARAMETER TYPE { 
domain; mUTl? 

min; 1 ; 
max: 32? 
default; -1; 
} 

PARAMETER DESCRIPTION { 

"Trunk and line workstation 



test 
} 



position number (1-32) 



FIG. 2a 
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200 REPORT { 

210 initiation message ( 

22 0 MGWSPOS? 

} 

230 TEMPLATE { 

240 proto; "OP WJPOS" ? 

250 protOi "TP" ! n ID" I "TO" l n FR£Q" ! "LVL ,J 

! "T&M MODE" J "OPD" ; 
26 0 proto 2 " — " i n — ii | M _ _ ii i ii - j ft n 

i — ii | m_ •( A 

t 

270 proto: tp lid ! to !fr«g I Ivl Jmode 

! opd; 

) 

260 PTJRPOSE ( 

250 -To list the current default of a 

TLWS (trunk and line worXstation) 
TP (test position) . This report 
is generated as a result of an 
OP-WSPOS Command, H 

i 

300 PARAMETER tp ( 

310 PARAMETER TtfPE { 

320 domain: nura; 

330 mini 1 ? 

340 max; 32; 

350 default: -1; 

) 

350 PARAMETER DESCRIPTION { 

370 -TLWS TP number (1-32)," 

} 

} 

330 PARAMETER id { 

390 PARAMETER TYPE { 

400 doni: num; 

410 min: 1; 

420 max: 32; 

430 default i 0; 



4 40 PARAMETER DESCRIPTION { 

4 50 "TP identification number « 

) 



FIG. 2b 
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PARAMETER to { 

PARAMETER TYPE { 
■domain : num; 
min : 1 ; 
max: 100; 
default t 1} 



PARAMETER DESCRIPTION { 

■Time in hours before the TP 
will timeout." 



PARAMETER freq { 

PARAMETER TYPE { 
domain: num.; 
min: 0; 
max: 4095; 
default: -I; 
> 

PARAMETER DESCRIPTION { 
•Frequency in hertz." 
} 



PARAMETER Ivl { 

PARAMETER TYPE { 
domain: nuxri? 
min : 0 ; 
max.: 490; 
default: -i f - 
} 

PARAMETER DESCRIPTION { 
"Laval in decibel© . " 
} 




FIG. 2c 
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7 DO PARAMETER mode { 

710 PARAMETER TYPE { 

720 domain x ENUMLIST 

730 ENUM TMSR < 

740 text: -TALK"; 

750 desc: 'User can talk and listen."; 

} 

760 ENUM MONITOR { 

770 text: "MHTR*; 

730 desc: "user can only listen. "; 

} 

790 ENUM TEST { 

800 text: "TEST* ; 

810 desc: "Phone on hold,"; 

} 

320 ENUM NONE { 

830 text : "NONE" ; 

•B<10 desc: "No T&M phone in use. 11 ; 

} 

} 

} 

> 

350 PARAMETER opd { 

860 PARAMETER TYPE £ 

370 domain: dn? 

} 

680 PARAMETER DESCRIPTION { 

890 "Outpulse digita." 

> 

> 



FIG. 2d 
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300 



Analyze command 
specification parse tree 




Identify list of commands or reports that should appear 
on same documentation page, and appropriate section 
or page where documentation should appear 




From FIG. 3c (A) 



310 



305 / ^ 

/COMMAND 
\keyword? 



-Kg) To FIG. 3d 



Enforce command documentation rules, If any, and copy command syntax 
and parameter information from TEMPLATE segment ol command specification 
into a header segment of a documentation file associated with the command 



315 



322 




Yes 



Enforce warning documentation 
nulea, if any, and copy associated 
character string into a warning 
segment of documentation file 



Place indication that there are 

no warnings In warning 
segment of documentation file 



1 



\ 

320 



FIG. 3a 



■PJTaFIG. 3b 
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325 



©From FIG. 3a 
\ 328 



X 



V 



PURPOSE \N< 
keyword?^ 



PURPOSES, 
keyword 



330 




Generate 
error message 



Enforce purpose documentation 
rules, If any, and copy associated 

character string into a purpose 
segment of the documentation file 



No 




Enforce parameter documentation rules, If 

any, and copy associated cnarader 
string into an explanation of parameters 
segment of the documentation fie 



348 



Yes 



Are 

there additional" 
parameters to be 
.documented?^ 



No 



No 



® To FIG, 3c 
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From FIG. 3b 



350 



354 




352 

.A 



Place an indication that 
only standard responses 
apply in a response segment 
of documentation file 



Enforce responses documentation 
rules, If any, and copy associated character 
string into a response segment of 
the documentation file 



355 



Are 

there additional" 
COMMAND keywords to^. 
be processed J?. 

No 

® To FIG. 3d 



Yes 



KA)To FIG. 3a 



FIG. 3c 
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360 




® From FIG. 3a, 3c or 3e 



<f REPORT \ No t{F , Tn 
X keyword? To FIQ - 3e 



382 



*Ves 



Enforce report documentation rules, if any and 
copy command name report heading end 
parameter information from TEMPLATE segment 
of report specification Jnto a header segment of 
a documentation file associated with the report 



364 



368 




Enforce purpose documentation rules, 
If any, and copy associated character' 
string Into a purpose segment 
of the report documentation fiJe 



Are 

there eddltlonaT 
^PURPOSE keywords to 
.be processed 2- 



369 



No, 



To FIG, 3e 



FIG. 3d 
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Generate 
error message 
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From FIG. 3d 




r PARAMETE 
DESCRIPTION 
keyword 
necessary? 



Enforce parameter documentation rules, If any, and 
ropy associated character siring into an explanation 
of parameters segment of the documentation file 



iV 

No 




378 



Yes 



Are there 

additional parameters to be^ 
documented?. 



NoL 



380 

'Are there 
^additional REPORT keywords' 
be processed ?. 



Yes 



<B)ToFIG. 3d 
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-© From FIG. 3d 



EXIT 



FIG. 3e 
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400 

\ 

OP-WSPOS COMMAND DOCUMENTATION FILE 



410 — . 

OP-WSPOS; TP - a 
415^-— Warning: none 



420 



425 



- PURPOSE 

Prints the current defaults for the indicated trunk and 
line workstation (TLWS) test position (TP). 



- EXPLANATION OF PARAMETERS 
a = Trunk and line workstation te$t position number (1-32). 



430 



RESPONSES 

Only standard system responses apply. 



FIG. 4 
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OP-WSPOS REPORT DOCUMENTATION RLE 

"OP WSPOS 

TP ID TO FREQ LVL T$JA MODE OPD 
^ h C d e f g 



> REPORT PURPOSE 

To list the current defaults of a TLWS (trunk and line work station} 
TP (tost position). This report Is generated as a result of an 
OP-WSPOS command. 



' EXPLANATION OF PARAMETERS 
a = TLWS TP number (1-32), 
b = TP identification number, 
c = Time in hours before the TP will timeout, 
d = Frequency in hertz, 
a = Level in decibels, 
f = T&M (talk and monitor) phone mode. 

MNTR - User can only listen. 

NONE - No T&M phone In use. 

TALK - User can talk and listen. 

TEST - Phone on hold, 
g = Outpulse digits. 



FIG, 5 



